SEP 12 -- 接口文档规范

Head

Author: larry
Status: draft
Type: Standards
Created: 2017-11-30

文档格式

格式举例

/datacenter/stock_in 入库列表

接口描述
    批量查询入库单
Method
    GET
请求
    ----- session (from cookie) -----
    station_id  M   string  站点ID
    ----- params -----
    start_date  M   datetime    查询开始日期
    end_date    M   datetime    查询截止日期
    offset      O   int         分页偏移量
    limit       O   int         分页每页限制数量
    query_data  O   string      查询内容，支持批号和客户ID
响应
    code    M   int     返回码，0表示成功，其他表示错误
    msg     M   string  错误信息
    data    M   string  返回json数据

    [{
        "batch_id"  M   string  批号
        "receipt_id"    M   string  入库单号
        "name"  M   string  商品名
        "ware_category_1_name"  M   string  仓库名
        "ware_category_2_name"  M   string  库区名
        "ware_category_3_name"  M   string  库位名
        "ware_category_4_name"  M   string  通道名
        "operate_date"  M   datetime    入库日期
        "in_count"  M   int 入库数
        "creator_id"    M   int 创建人ID
        "creator_name"  M   string  创建人名
    }]
逻辑  // 可选
    对一些简单的查询逻辑，这里可以为空。
    对一些有特殊逻辑的地方，这里要写明特殊的逻辑。
    对一些较为复杂的接口，这里需要写上伪代码。
示例  // 可选
    request
        http://test.guanmai.cn:8888/datacenter/stock_in
    response
        {
            "pagination": {
                "limit": 10,
                "count": 71,
                "offset": 0
            },
            "data": [{
                "name": "sdf",
                "creator_name": "superman",
                "receipt_id": "RK00009",
                "in_count": 20,
                "creator_id": 1,
                "operate_date": "2016-09-07",
                "batch_id": "213-1",
                "ware_category_1_name": "C1_1",
                "ware_category_3_name": "W1",
                "ware_category_4_name": "T1",
                "ware_category_2_name": "K2"
            }],
            "msg": "ok",
            "code": 0
        }

/datacenter/stock_in/export 入库列表导出

接口描述
    入库单导出
Method
    POST
请求
    ----- session (from cookie) -----
    station_id  M   string  站点ID
    ----- params -----
    start_date  M   datetime    查询开始日期
    end_date    M   datetime    查询截止日期
    offset      O   int         分页偏移量
    limit       O   int         分页每页限制数量
    query_data  O   string      查询内容，支持批号和客户ID
响应
    xlsx文件
逻辑  // 可选
    复杂接口需要写上具体逻辑
示例  // 可选
    request
        http://test.guanmai.cn:8888/datacenter/stock_in/export
    response

格式定义

排版

接口标题

用markdown head格式。比如：

### /datacenter/stock_in/export 入库列表导出

接口内容

缩进四个空格，用code block格式。block内部的子标题，不再使用head格式，只能整体作为一个block文本块，与自己的上级标题缩进四个空格。下面是错误的格式。

## /datacenter/stock_in/export 入库列表导出
### 接口描述
    入库单导出
### Method
    POST
### 请求
    ----- session (from cookie) -----
    station_id  M   string  站点ID
    ----- params -----
    start_date  M   datetime    查询开始日期
    end_date    M   datetime    查询截止日期
    offset      O   int         分页偏移量
    limit       O   int         分页每页限制数量
    query_data  O   string      查询内容，支持批号和客户ID
### 响应
    xlsx文件
### 逻辑  // 可选
    复杂接口需要写上具体逻辑
### 示例  // 可选
    request
        http://test.guanmai.cn:8888/datacenter/stock_in/export
    response

下面是正确的格式

## /datacenter/stock_in/export 入库列表导出
<换行>
    接口描述
        入库单导出
    Method
        POST
    请求
        ----- session (from cookie) -----
        station_id  M   string  站点ID
        ----- params -----
        start_date  M   datetime    查询开始日期
        end_date    M   datetime    查询截止日期
        offset      O   int         分页偏移量
        limit       O   int         分页每页限制数量
        query_data  O   string      查询内容，支持批号和客户ID
    响应
        xlsx文件
    逻辑  // 可选
        复杂接口需要写上具体逻辑
    示例  // 可选
        request
            http://test.guanmai.cn:8888/datacenter/stock_in/export
        response

接口标题 -- 必选

格式

<head级别> <接口路径> <接口中文名>

说明

head级别：根据上下文决定。
接口路径

url中的path部分，比如/datacenter/stock_in/export，不是http://test.guanmai.cn:8888/datacenter/stock_in/export。
接口中文名：一个简短的中文名，方便目录索引。

接口描述 -- 必选

对接口内容做一个简短的描述，某些情况下跟接口名会有些重复。

Method -- 必选

目前只有，GET和POST两种，如果有其他的也可以用。

请求 -- 必选

描述所有与请求相关的内容。

举例：

----- session (from cookie) -----
station_id  M   string  站点ID
----- params -----
start_date  M   datetime    查询开始日期
end_date    M   datetime    查询截止日期
offset      O   int         分页偏移量
limit       O   int         分页每页限制数量
query_data  O   string      查询内容，支持批号和客户ID
----- file upload -----
<binary data...>

请求参数分类

用分断线做个简单的分类，目前已知的分类有：session(from cookie), params（get/post都算）, file upload。如果有更多分类，按照类似方法写。
参数格式

见后面

响应 -- 必选

描述所有与输出相关内容。

输出分两类。

文本类输出

{
    "code": 0,
    "msg": "ok",
    "data": {
        "id": "WB000002",
        "ware_category_1_name": "A1",
        "delete_time": "2016-10-31",
        "create_time": "2016-06-04",
        "ware_category_2_name": "B1"
    }
}

下载文件

下载成功，返回二进制内容。

<binary data...>

下载失败，返回错误信息。

{
    "code": 错误码,
    "msg": "错误信息",
    "data": null
}

返回字段定义：

code -- 必选

返回码，成功时为0，错误时为具体错误码。
msg -- 必选

返回信息。错误时是具体的错误信息，成功时通常为OK。
data -- 必选

返回业务数据的容器。

举例：
```
"data": {
        "id": "WB000002",
        "ware_category_1_name": "A1",
        "delete_time": "2016-10-31",
        "create_time": "2016-06-04",
        "ware_category_2_name": "B1"
        }
```
举例：
```
"data": [{
        "id": "WB000002",
        "ware_category_1_name": "A1",
        "delete_time": "2016-10-31",
        "create_time": "2016-06-04",
        "ware_category_2_name": "B1"
        }]
```
作为容器，data的值可以是dict或者list，但不能是基本类型int或者string。所有的返回值应该以合理的方式包装在dict或者list里。

举栗，create接口要返回新记录的id字段，正确的返回应该是：
```
"data": {
    "id": "WB000002",
}
```
而不是
```
"data": "WB000002"
```
为什么不能用后一种方式，因为这种用法，等于data成了这个值的变量名，但data是世界上最差的变量命名。原则上，list也有这种隐患，但是因为返回list的情况下，接口的命名通常能非常明确的反映出返回内容的含义，所以在不引起误会的情况下，list也是可接受的。如果list不能清晰表达返回的含义，仍然建议用dict。

data中的格式

格式举例：

[{
    "ware_category_1_name"  M   string  仓库名
    "ware_category_2_name"  M   string  库区名
    "freeze_fees": [{   O   list    冷藏费
        "name"  M   string  商品名
        "charge_count"  M   float   计费数量
        "should_pay"    M   float   应付金额
        "days"  M   int 天数
        "customer_name" M   string  客户名
        "batch_id"  M   string  批号
        "end_date"  M   datetime    截止日期
        "start_date"    M   datetime    起算日期
        "unit_name" M   string  单位
        "unit_price"    M   float  单价
        "customer_id"   M   string  客户ID
        "real_count"    M   float   实际数量
    }],
    "other_fees": [{    O   list    杂费
        "should_pay"    M   float   应付金额
        "customer_name" M   string  客户名
        "batch_id"  M   string  批号
        "name"  M   string  商品名
        "charge_count"  M   float   计费数量
        "unit_name" M   string  单位
        "type"  M   string  杂费名称
        "unit_price"    M   float   单价
        "customer_id"   M   string  客户ID
        "real_count"    M   float   实际数量
    }]
}]

整体结构

使用json默认的方式，保留良好的结构缩进(pretty print)便于阅读。

容器类型 - dict

<字段名> { <字段可选性> dict <字段描述>。
比如：
    "other_fees": {    O   dict    杂费
不要写成下面这种
    "other_fees": 
        {    O   list    杂费
    上面的"{"应该与容器字段名放在同行

容器类型 - list

<字段名> [ <字段可选性> list<syb-type> <字段描述>。
比如：
    "other_fees": [{    O   list<dict>    杂费
    "name_list": [    O   list<str>    名字列表

基本类型

<字段名> <字段可选性> <字段类型(min,max)> <字段描述>。
例如：
    "customer_id"   M   string  客户ID
详情定义见后面参数格式部分。

逻辑 -- 可选

逻辑部分需要描述接口内部逻辑的基本流程，类似伪代码。

如果是一些简单的查询，可以不用写。

示例 -- 可选

对于结构略复杂的返回，最好有示例。

request
        http://test.guanmai.cn:8888/datacenter/finance/ware_fee?start_date=2016-10-02&end_date=2016-10-02
response
    {
        "code": 0,
        "msg": "ok",
        "data": [{
            "ware_category_1_name": "mila-b",
            "ware_category_2_name": "b2"
            "freeze_fees": [{
                "name": "100003a",
                "charge_count": 1.5,
                "should_pay": 90.0,
                "days": 5,
                "customer_name": "客户20",
                "batch_id": "100003-1",
                "end_date": "2016-09-20",
                "start_date": "2016-09-16",
                "unit_name": "吨",
                "unit_price": 12.0,
                "customer_id": "K00079",
                "real_count": 1.245
            }],
            "other_fees": [{
                "should_pay": 34.5,
                "customer_name": "客户20",
                "batch_id": "100003-1",
                "name": "100003a",
                "charge_count": 1.5,
                "unit_name": "吨",
                "type": "处置费",
                "unit_price": 23.0,
                "customer_id": "K00079",
                "real_count": 1.25
            }]
        }]
    }

参数格式

格式定义

<参数名> <参数可选性> <参数类型(min,max)> <参数描述>
参数可选性 -- 必选

M：must，必选参数 O：optional，可选参数 C: conditional，某些条件下必选，请在"参数描述"字段说明具体的条件
参数类型(范围) -- 必选

参数类型 -- 必选

str([min,]max)：字符串。
    举例：     query_data  O   string(128)      查询内容，支持批号和客户ID，最长128
int([min,]max)：整数，注意这里不单独再区分int和bigint了，统一为64位。
    举例：     limit       O   int         分页每页限制数量
datetime：日期时间，格式 2017-10-22 10:22:35
    举例：     start       M   datetime    开始时间
date：日期，格式 2017-10-22
    举例：     start_date  M   date        开始日期
time：时间，格式 10:22:35
    举例：     start_time  M   time        开始时间
enum<int>：int型枚举，请列出枚举的可选值。
    举例：     query_type  M   enum<int>   查询类型。可选值: 1 - 站点，2 - 加盟商， 3 - 供应商。
enum<str>：str型枚举，请列出枚举的可选值。
    举例：     query_type  M   enum<str>   查询类型。可选值: 1 - 站点，2 - 加盟商， 3 - 供应商。
json<list>：json list类型，注意我们是要urlencode的串。
    举例：     partner_list  M   json<list>   加盟商列表[1, 2, 3, 4]
json<map>：json map类型，注意我们是要urlencode的串。
    举例：     partners  M   json<map>   加盟商 {1: "加盟商A", 2: "加盟商B", 3: "加盟商C"}

范围 -- 可选建议填写，比如string(15)表示字符串最长15。string(2, 15)表示最小2最大15。这部分未来可能要做成字段定义字典，统一一个长度，待讨论。
参数描述 -- 可选除非特别简单的字段，建议都写上。

接口命名

REST

参考rest风格，考虑我们的实际情况，暂时不能完全符合rest规范。

rest的风格实际类似面向对象的命名风格。

Method

目前我们只是用了GET和POST两种。

GET操作不会对系统状态发生变更，比如查询。POST操作会对系统状态发生改变，比如修改，或者动作类。

Path

按照rest推荐的风格，应该是下面这种。

/资源/子资源/子资源/动作

不排除有例外，但是尽量遵守。

动作

查询类

单对象查询：get。
批量查询：list。

修改类操作

创建：create
修改：update
删除：delete

动作类

根据实际情况取名，反映具体的业务动作。

有些操作既可以用动作类表达，也可以用修改表达，优先用具体业务动作表达，以更清晰的表述操作含义。

用进销存中的操作举例：

审核(review)

审核操作，审核(review)本身完成后也许只做了状态的变迁，从数据上说，确实是只做了状态更新(update)，但审核更能表达明确的业务语义，更新过于通用。所以审核应该用review，而不是update。
冲销(cancel)

对入库记录来说，冲销只是做了状态修改，但是不同于普通的update，冲销还要做其他内容，比如库存变动，所以这里不能用update。